home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _utilities / utilities / 004 / _spconv / !Spconv / Doc / Spconv < prev    next >
Text File  |  1994-04-02  |  12KB  |  326 lines
  1.  
  2.  
  3. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  4.  
  5.  
  6. NAME
  7.  
  8.      spconv - Convert snapshot files (.SNA, .SP, .Z80,  .PRG,  .ACH,  .ZX  and
  9.      RAW)
  10.  
  11.  
  12. DISCLAIMER
  13.  
  14.      This programs are Public Domain, and because of that I will not be liable
  15.      for any damages resulting from use of this software.
  16.  
  17.  
  18. SYNOPSIS
  19.  
  20.      spconv <infile.EXT> <.EXT>
  21.      spconv <infile.EXT> <outfile.EXT>
  22.  
  23.  
  24. DESCRIPTION
  25.  
  26.      Spconv is a utility to convert between various snapshot formats. Snapshot
  27.      files  are created by various spectrum emulators. SPCONV converts between
  28.      .SNA, .SP, .Z80, .PRG, .ACH and .ZX files.
  29.  
  30.      Wildcards for the infile or outfile parameters are not accepted, an error
  31.      message  is  displayed  if  either  *  or  ?  is found in one or both the
  32.      filenames. The outfile parameter is either a full filename  or  only  the
  33.      suffix  .SNA,  .SP, .Z80, .PRG, .ACH or .ZX. The prefix is taken from the
  34.      first parameter in that case.
  35.  
  36.      Normaly the <infile> and <outfile> are not of the same type. If they  are
  37.      you will get a error message. This is so unless both files are of the .SP
  38.      or .Z80 type. In case of .SP format the converter  will  convert  an  old
  39.      style .SP file to a new style .SP file or from a new style .SP file to an
  40.      old style .SP file, depending on the input. The old  style  .SP  file  is
  41.      used  by VGASPEC, with seems to be an unauthorised version of the spanish
  42.      "SPECTRUM" program. The "SPECTRUM" program will use  the  new  style  .SP
  43.      files.
  44.  
  45.      In case both files are of the .Z80 format spconv will read the .Z80  file
  46.      and will output a .Z80 file in the version 1.45 .Z80 format. This enables
  47.      conversion of normal 48K Spectrum files made by Z80 version 2.01  to  the
  48.      older  format  so  they  can be loaded in a version 1.45 Z80 emulator. Of
  49.      course additional information that can only be stored in the version 2.01
  50.      files that is lost. Therefore spconv will check if the .Z80 file is for a
  51.      48K Spectrum and check if the Interface-1 rom was not paged  in.  If  the
  52.      check  fails an error message is given and the conversion is terminated -
  53.      no output will be produced. Spconv will only  output  version  1.45  .Z80
  54.      files since these are compatible with old and new Z80-emulator versions.
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                                03rd May, 1994                                1
  65.  
  66.  
  67.  
  68. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  69.  
  70.  
  71. CONVERSION NOTES
  72.  
  73.      [.SP files - Used by the Spanish "SPECTRUM" and "VGASPEC" programs.]
  74.  
  75.      Conversion to/from .SP files may not always work. It is not clear  to  me
  76.      how  IFF,  IFF2  and the interrupt mode are stored in the .SP file. Since
  77.      version 1.02 I have made some improvements to  this  type  of  conversion
  78.      however,  it  sould  work now, but I have not enough .SP samples to fully
  79.      test it. Note that crashing of a converted image may also  be  caused  by
  80.      bugs  in  the SPECTRUM emulator. Conversion to .SP will work if the image
  81.      is converted from a RAW image (see later).
  82.  
  83.      [.Z80 files - Used by the Dutch  "Z80"  programs.  This  format  is  also
  84.      usable for 128K Spectrum images.]
  85.  
  86.      [.SNA files - Used by the  Norwegian  "JPP"  PC-program;  the  "Spectrum"
  87.      program  for  the Amiga; the "XZX" X-Windows program and a lot more. This
  88.      is the most  supported  format  since  it  originated  from  the  Mirage-
  89.      Microdirver format.]
  90.  
  91.      Conversion between .SNA and .Z80 and from  .Z80  to  .SNA  should  be  no
  92.      problem,  both formats are sufficiently described in the documentation of
  93.      JPP (the norwegian emulator) and Z80 (the dutch emulator).
  94.  
  95.      [.PRG files are loaded by a PC-emulator from Ireland. This  emulator  can
  96.      not save in this format.]
  97.  
  98.      Conversion to/from .PRG files should work  fine  also.  I  don't  have  a
  99.      description  of  that format, but I think I figured it all out by looking
  100.      at some samples. I only don't know where the border colour is stored. The
  101.      specem  emulator  (an Irish emulator) doesn't show the border, so I can't
  102.      find out by trail and error.
  103.  
  104.      [.ACH files are  used  on  Archimeds  computers  by  an  emulator  called
  105.      "Speculator" or "!Speccy"]
  106.  
  107.      Since  version  1.07  Conversion  should  work  without   problems.   The
  108.      conversion  is  patterned after a program (also called Spconv) and a BBC-
  109.      Basic program from John Veness (supplied to me by Mike Borcherds). I also
  110.      got a .ACH file snapped just after startup which was most helpfull. Since
  111.      the programs I got were written independently but had  all  registers  at
  112.      the  same place (but one got her accent registers swapped with the normal
  113.      registers), I think it is pritty  save  to  assume  that  the  format  is
  114.      correct now. The previous version of this converter got register 'I' from
  115.      the wrong spot, and more important, I forgot to set  the  interrupt  mode
  116.      when converting to .ACH file format.
  117.  
  118.      It is also tested now with a fair collection of snaps. The .ACH extension
  119.      is  my  own invention to cope with the MS-DOS naming conventions. I named
  120.      them this way because the samples I had ended in ".archimedes" and use of
  121.      .ARC  as  extension  didn't  sound  like  a  good  idea.  I don't have an
  122.      archimedes computer to test it but somebody else (Adrian Jackson) did  it
  123.      for me. For proper conversion you need the spectrum rom because that is a
  124.      part of the archimedes image (don't blame me).  The  ROM  must  be  named
  125.      'spectrum.rom'  and  be  located  in the working directory or in the same
  126.      directory as spconv.exe. If no ROM is found  the  converter  will  insert
  127.  
  128.  
  129.                                03rd May, 1994                                2
  130.  
  131.  
  132.  
  133. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  134.  
  135.  
  136.      NULL bytes.
  137.  
  138.      [.ZX files are used by the KGB emulator on a Commodore Amiga]
  139.  
  140.      Conversion to/from .ZX files should  work,  Peter  McGavin  send  me  the
  141.      definition  of  the format as used in the KGB emulator. I implemtented it
  142.      that way but I don't have an Amiga with a KGB emulator so it is untested!
  143.      I  previously  used  the  information about the format of the file from a
  144.      VAX-Basic program supplied to me by  Jason  Brown  and  most  information
  145.      correlated  so  I'm hopefull that it works. Please send me feetback if it
  146.      works so I can put it here in the documentation. Oh, before I forget, the
  147.      .ZX  format contains the last 132 bytes of the spectrum rom (don't ask me
  148.      why) so spconv will look for "spectrum.rom" in the working  directory  or
  149.      in the same directory as spconv.exe is located.  If absent than the first
  150.      132 bytes will be NULL bytes.
  151.  
  152.      [RAW files are created by saving the whole ram on a real spectrum to  the
  153.      RS232 port of Interface-1 from basic]
  154.  
  155.      Spconv can also be used to convert a raw spectrum  image  to  a  snapshot
  156.      file.  The  image  has  to  be  captured  with via the RS232 connetion on
  157.      Interface-1.  Some tools to do this are in an archive called "SPEC232". A
  158.      program  called  "SLOAD"  will  read from the RS232 link to a file on the
  159.      MSDOS-PC. At the Spectrum side the the command
  160.  
  161.      SAVE *"b"CODE 16384,49152
  162.  
  163.      HAS to be used. Spconv will convert the file is such  way  that  it  will
  164.      continue in the basic interpreter after the snapshot is loaded. so
  165.  
  166.      SAVE *"b"CODE 16384,49152:PRINT Hello, World!
  167.  
  168.      will after conversion to a snapshot file and loading it in  the  emulator
  169.      begin  with printing "Hello, World!". A description how to wire the RS232
  170.      cable is also in the "SPEC232" package.
  171.  
  172.  
  173. EXAMPLES
  174.  
  175.      Converting a .SNA JPP file to the .Z80 Dutch emulator:   spconv  game.sna
  176.      game.z80 or spconv game.sna .z80
  177.  
  178.  
  179. DIAGNOSTICS
  180.  
  181.      0 - OK: The program finished without problems
  182.  
  183.      1 - USAGE:  The program was called incorrectly:
  184.  
  185.          -    Wrong number of parameters
  186.  
  187.          -    Wildcards on the command-line
  188.  
  189.          -    Input and output are of the same type (not for .SP and .Z80)
  190.  
  191.  
  192.  
  193.  
  194.                                03rd May, 1994                                3
  195.  
  196.  
  197.  
  198. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  199.  
  200.  
  201.      2 - READ_ERROR:  There was a problem while reading the input file:
  202.  
  203.          -    Error while reading the input file
  204.  
  205.          -    Error while fseeking the input file
  206.  
  207.      3 - WRITE_ERROR: There was a problem while creating the output file:
  208.  
  209.          -    Error while writing the output file
  210.  
  211.          -    Error with opening/reading the spectrum.rom needed  for  the  output
  212.               file.
  213.  
  214.      4 - FILE_ERROR:  There was a  problem  with  the  input  or  output  file
  215.          format:
  216.  
  217.          -    Input file does not exist
  218.  
  219.          -    Type of input or output file not known
  220.  
  221.          -    Input file is:
  222.  
  223.               +    A newer version of an existing type
  224.  
  225.               +    Corrupt
  226.  
  227.               +    Not in the expected format (RAW and new .SP types)
  228.  
  229.               +    Not a 48K spectrum file (in .Z80 files)
  230.  
  231.          -    Input file snapshot was taken while the interface-1 was paged in (in
  232.               .Z80  files).  The  other  file  formats  can  not  cope  with  this
  233.               (including the version 1.45 .Z80 files).
  234.  
  235.          -    Undocumented page number in .Z80 files (file corrupt).
  236.  
  237.          -    Decompression of .Z80 file failed (file corrupt).
  238.  
  239.  
  240. PORTABILITY
  241.  
  242.      The program should be portable. Assumptions about endian-ness are avoided
  243.      and  I  ensured  clean  compilation with Turbo-C++ 1.0 (with all warnings
  244.      enabled).  Chris Wells used this command line of GCC on this program (and
  245.      gave feetback until it gave a clean compile):
  246.  
  247.      gcc -ansi -pedantic -Wall -Wwrite-strings  -Wshadow  -Wformat  -Wpointer---
  248.      arith  -Wconversion  -Wstrict-prototypes  -Wmissing-prototypes  -o spconv
  249.      spconv.c
  250.  
  251.  
  252.      I also ensured that the identifiers used in the program are uniq  in  the
  253.      first  8  characters.  I  don't  expect  much problems when compiling the
  254.      program with other compilers. The code does make assumptions  about  path
  255.      names.   Using  the  program on a VAX will give problems with recognizing
  256.      directories e.t.c. especially for finding "spectrum.rom", I leave  a  fix
  257.  
  258.  
  259.                                03rd May, 1994                                4
  260.  
  261.  
  262.  
  263. SPCONV(1)                  Unix Programmer's Manual                  SPCONV(1)
  264.  
  265.  
  266.      for this as an exercise...
  267.  
  268.  
  269. BUGS
  270.  
  271.      Conversion to/from .SP files may not always work.
  272.  
  273.  
  274. THANKS TO
  275.  
  276.      Thanks  for  suppling  information  and  for  creating   these   spectrum
  277.      emulators:
  278.      Arnt Gulbrandsen (author of JPP)
  279.      Ramco v.d. Woestijne (supplied new .SP format);
  280.      Gerton A. Lunter (author of Z80);
  281.      Pedro Gimeno (author of SPECTRUM);
  282.      Kevin J Phair (author of SPECEM);
  283.      Mike Borcherds (suppied the archimedes file format);
  284.      Jason Brown (suppied the initial KGB file format);
  285.      Peter McGavin (suppied the complete KGB file format);
  286.      John Veness (reverse engineerd the ACH file format);
  287.      Adrian Jackson (send me a near perfect .SNA to .ACH converter);
  288.      Chris Wells (ran the program through GCC in pedantic  mode  and  supplied
  289.      the UNIX man page and Makefile).
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.                                03rd May, 1994                                5
  325.  
  326.